feat(powersync-db-collection): support numeric collection keys - #2392

Implements #2391.

What changes

A deserializationSchema may now convert id to a number, for example id: z.coerce.number(). This is for backends with integer primary keys. The collection key is the deserialized id, so integer foreign keys match it: eq(part.id, line.partId) compares 5 with 5.

Before this change, getKey threw Record must have a string id field.

Every path that writes a collection key now takes the key from the deserialized row, not from SQLite's text id:

• Initial and on-demand loads: getKey(deserializeSyncRow(row)).
• Reload update or insert choice (collection.has): it now gets the deserialized key. With the raw text id, it would never match a numeric key.
• Tracking-outage sweep (missing.delete): it now runs inside writeType, using the same key. With the raw text id, it removed nothing, so every held row was deleted.
• Unload eviction: the discussion did not list this path. It ran SELECT id … and deleted keys by the raw text id. It now selects the rows and deserializes them. The type checker found this path once the key type was derived from the row.
• Local updates and deletes: these write String(mutation.key) to WHERE id = ?. This matches how the serializer already writes a numeric id on insert ("5"), and how the PowerSync service converts integer ids (idFromData). So writes work too; collections with numeric keys are not read-only.

asPowerSyncRecord is removed. On the type side, PowerSyncRecord and AnyTableColumnType allow id: string | number. The collection key type is InferPowerSyncKey<Output>: number when the output id is a number, otherwise string. Existing string and branded-string collections keep string keys, and the existing type tests pass unchanged.

Evidence

PowerSync has no oracle owner. The coverage map lists it as "Fixed tests only" (tracked in #2264). So this PR adds focused tests in tests/numeric-keys.test.ts, one for each path. They run against a real node:sqlite PowerSync database.

• Law: the collection key is the deserialized row's id. Every key that sync writes, and every id that a local write sends to SQLite, refers to the same row. Authority: the collection's getKey contract and the discussion's proposal ([PowerSync] Support integer primary keys: the collection key must be a string `id` #2391).
• Reach: eager load, SQLite update and delete, local update and delete, on-demand reload with held rows, unload eviction, and the release-rebuild tracking outage. All use numeric keys.
• RED: run pnpm vitest run tests/numeric-keys.test.ts with src from main. All 3 tests fail.
• GREEN: the same command passes 3/3. The full package passes 198/199. The one failure is portable-declarations.test.ts, which fails locally with EPERM on symlinkSync (Windows symlink permissions) and has nothing to do with this change.
• Mutants: each one fails a test.
  • writeType(row.id): the outage test fails.
  • Eviction with key: row.id: the reload/eviction test fails.
  • mutation.key without String(...): the write test fails.
• Limits: no generated histories. These are fixed examples, consistent with the package's current coverage status. Not covered: keys that are neither strings nor numbers, and a custom serializer for id.

Size

Gzip of the minified dist/esm files: 8585 → 8543 bytes (−42). pnpm size:compare did not run on my machine: its baseline worktree build of db-ivm failed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • PowerSync collections support numeric IDs as collection keys when IDs are converted to numbers during deserialization. Numeric keys work with syncing, on-demand reloads, eviction, and local updates and deletes.
• Documentation
  • Added guidance for configuring integer primary keys and looking up records by numeric key. The guide also explains how updates and deletes handle IDs and how integer IDs are represented when syncing.